home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.2 Applications 1996 May / SGI IRIX 6.2 Applications 1996 May.iso / dist / impr_dev.idb / usr / impressario / doc / gui_model.spec.z / gui_model.spec
Text File  |  1996-05-06  |  9KB  |  206 lines
  1. GRAPHICAL MODEL FILE SPECIFICATION
  2.  
  3. $Revision: 1.15 $
  4. $Date: 1996/01/26 17:41:05 $
  5.  
  6.  
  7. Overview
  8.  
  9. Silicon Graphics printing technology includes a graphical print job submittal 
  10. Motif compatible widget, the PrintBox. The PrintBox widget is contained in the
  11. library, libprintui. Applications such as glp use the PrintBox widget to
  12. provide their printing capabilities. In addition to providing graphical
  13. selection of System V print job submittal options, the PrintBox provides a
  14. mechanism for graphical selection of printer specific options. This mechanism
  15. is the graphical model file. Graphical model files, also referred to as
  16. graphical options panels and gui_models, provide the printer vendor and driver
  17. developer a means to showcase the unique features of a printer in a
  18. visually-appealing graphical mode.  The graphical model file program is easily
  19. integrated into the PrintBox widget. This specification provides the
  20. information necessary to create a graphical model file and integrate it into
  21. SGI's printing technology.
  22.  
  23. Graphical model files are standalone executable programs.  These programs 
  24. are stored in a standard directory known to the PrintBox widget.
  25. The graphical model files are thus automatically available to users of the
  26. SGI printing tools that use the PrintBox widget (e.g. glp and Insight).  The
  27. rules for developing a graphical model file are straightforward and do not
  28. require any interprocess communication or similar complex procedures.
  29.  
  30.  
  31. Layout
  32.  
  33. Typically a graphical model file consists of a single window. This window 
  34. usually contains two main sections, an option section and an action area.
  35.  
  36. The option section contains all printer-specific option controls. This area 
  37. is often divided into groups of option controls, where each group represents
  38. a specific print file type. Most option areas contain controls for text files,
  39. SGI image format files, PostScript files and a general options section. Since
  40. there are often a large number of controls in the option section, a scrolled
  41. window should be used to keep the graphical model file window to a reasonable
  42. size.
  43.  
  44. The action area is located at the bottom of the graphical model file window and 
  45. consists of a number of push buttons. At a minimum, the graphical model file 
  46. must include these three action area buttons:
  47.  
  48. o    OK  - output option string to stdout and terminate program.
  49.  
  50. o    Apply - output option string to stdout but do not terminate program.
  51.  
  52. o    Cancel - terminate program without any option string output.
  53.  
  54. The following buttons may be include at the developer's discretion:
  55.  
  56. o    Help - provide printer specific options help.
  57.  
  58. Buttons should be grouped together on the right side of the action area. The 
  59. width of all buttons should be equal. The leftmost buttons should be OK 
  60. followed by Apply, Cancel and Help. Any additional buttons should be placed 
  61. between the Apply and Cancel buttons.
  62.  
  63.  
  64. Options Handling
  65.  
  66. When the OK or Apply buttons are activated, the graphical model file program 
  67. must form a valid System V printer option string based on its GUI settings and 
  68. print this string to its standard output (stdout).
  69.  
  70. If printer specific options have been passed to the graphical model file on the 
  71. command-line, the program must interpret those options and initialize its 
  72. option area controls to reflect these command-line options. Those options 
  73. that are not recognized by the graphical model file must be preserved and 
  74. prepended to the output option string.
  75.  
  76.  
  77. Graphical Model File Development
  78.  
  79. The graphical model file should be created with the OSF/Motif UI toolkit.  
  80.  
  81. As of Impressario 1.2 a graphical model file can have its own application
  82. resource file. While the resource file can be given any name, it is highly
  83. recommended that the name represent the printer model name and have
  84. its first letter capitalized. For example, the application resource file for
  85. the HP LaserJet graphical model file is called LaserJet. The name chosen
  86. for the resource file must be specified in the gui_class.h header file and
  87. must also be specified in the printer model file as the value of the GUI_CLASS
  88. variable. The resource file should be installed in the directory
  89. /usr/lib/X11/app-defaults.
  90.  
  91. To match the look and feel of the PrintPanel program (a.k.a glp) and other
  92. graphical options panels, the application resource file should include the
  93. following resources:
  94.  
  95. *useSchemes:            all
  96. *schemeFileList:        SgiSpec
  97. *sgiMode:               True
  98.  
  99. To facilitate localization of the option panel for international customers,
  100. all label strings and messages should be placed in the application resource
  101. file rather than being hard coded into the program.
  102.  
  103. The graphical model file must consist of a single executable program and its
  104. application resource file.  The graphical model files are restricted to a
  105. single executable and resource file because the printer installation tools
  106. install only these two files during network printer installation.
  107.  
  108.  
  109. Graphical Model File Naming
  110.  
  111. The graphical model file must be given the exact same name as its printer's 
  112. model file, followed by the suffix .gui.  For example, if the printer model
  113. file for an HP DeskJet 500C printer is called dj500c_model, then the graphical
  114. model file must be given the name dj500c_model.gui. If the graphical model
  115. file is given a name which differs from the model file name, the graphical
  116. model file will not be installed when a new printer is installed on a system.
  117.  
  118. The application resource file for the graphical model program should be given
  119. a name representative of the printer's model name (e.g. LaserJet). Typically,
  120. the first letter of the resource filename is capitalized. The name of the
  121. resource file must be specified in the gui_class.h file as the value of the
  122. GUI_CLASS define and in the printer model file as the value of the GUI_CLASS
  123. variable.
  124.  
  125.  
  126. Installation
  127.  
  128. Graphical model file programs must be installed in the directory
  129. /var/spool/lp/gui_model/ELF.  
  130.  
  131. The printer installation software looks in the above directories for
  132. graphical model file programs.  The executable should be owned by lp
  133. and should be a member of the group lp. The executable should be
  134. given 0755 file permissions.
  135.  
  136. Graphical model file programs should be compiled on Irix 5.3 (or
  137. higher) to support Impressario versions 2.0 (and higher).  
  138.  
  139. The application resource file for the program should be installed
  140. into /usr/lib/X11/app-defaults. The file should be given 0644
  141. permissions and should be owned by the root user and sys group.
  142.  
  143.  
  144. Invocation by the PrintBox widget
  145.  
  146. Typically the graphical model file is invoked by the PrintBox widget. The
  147. graphical model file will always be invoked with the following command line
  148. arguments:
  149.  
  150.     argv[0]        printer name
  151.  
  152.     argv[1]        user name
  153.  
  154.     argv[2]        filename(s) string
  155.  
  156.     argv[3]        printer-specific option string (optional)
  157.  
  158.     argv[4-n]    Xt options (optional)
  159.  
  160. Note that any Xt options must be specified as argv[4] or greater.  If there
  161. are no printer-specific options for argv[3], the empty string ("") will be
  162. passed as argv[3].  Similarly, if no filenames are specified, the empty
  163. string will be passed as argv[2].
  164.  
  165. You must use the printer name (i.e. argv[0]) as the instance name of the
  166. application. This is done automatically if the main program from the
  167. sample graphical model source code is used. The PrintBOx widget will not
  168. recognize that the graphical model program has appeared on the screen if
  169. the graphical model program is not given the printer name as its instance
  170. name.
  171.  
  172.  
  173. Standalone Invocation
  174.  
  175. To test a graphical model file during development, it may be run as a 
  176. standalone executable from the UNIX command line.  Invoke the graphical 
  177. model file by entering:
  178.  
  179.     [executable name]  [any valid username]  ""
  180.  
  181. For example, if the executable program is called dj500c_model.gui, and "joe" is 
  182. a valid username on the system, then the program can be executed from the 
  183. command line by typing:
  184.  
  185.     dj500_model.gui joe ""
  186.  
  187. If the application resource file is located only in the current directory,
  188. the environment variable XUSERFILESEARCH path should have a '%N' prepended
  189. to it so that resource files are looked for in the current directory. Doing
  190. this will ensure that the graphical model file program finds its resource
  191. file in the current directory.
  192.  
  193.  
  194. Termination by the PrintBox
  195.  
  196. When the application using the PrintBox widget terminates the graphical model
  197. file will be sent a SIGTERM or a SIGHUP. The graphical model file should exit
  198. upon receipt of either of these signals. This is the default behavior for
  199. these signals.
  200.  
  201.  
  202. Example Code
  203.  
  204. Example source code for graphical model files can be found on-line in the 
  205. directory /usr/impressario/src/gui_models.
  206.